Skip to main content

Deploying pdf2Data Editor with a helper script

This guide describes the installation process using a helper deployment script

Installation video​

~10 min

Introduction​

To successfully install pdf2Data Editor, it is necessary to prepare configuration files that properly configure the Docker environment beforehand. To streamline the installation process, we recommend using deployment scripts that are available for each released version of pdf2Data, starting with 4.0.

Among other handy functionalities, the scripts automatically create configuration files.

caution

Scripts are written in Kotlin. so unlike manual installation, Kotlin complier must be installed (see the next section)

Prerequisites​

Since pdf2Data Editor is provided as Docker containers, we assume that you have some familiarity with containerization, particularly with Docker Compose.

To deploy and start the app, the following software must be pre-installed.

All pdf2Data Editor components are available as images on DockerHub Your system must be able to access it.

Download the script​

To deploy a specific version of pdf2Data Editor, you need to Download from artifactory the corresponding script. Once downloaded, save the script in an empty folder on the disc.

For instance:

  1. If you want to install pdf2Data 4.2.0 then you need to use deploy-docker-compose-4.2.0.main.kts file.
  2. While updating your application pdf2Data 4.b.c to 4.y.z, you need the script called deploy-docker-compose-4.y.z.main.kts

Application directory​

This directory is where you saved the deployment script and it's an irreplaceable part of the application deployment.

The application directory is used by the script to create the necessary files for running the application such as binaries, configuration, temporary files, and backups.

To make sure that everything works correctly, the directory should be:

  1. initially empty
  2. writable for the Kotlin compiler.

List of available commands and parameters​

To view available commands and parameters in the script, execute the following command in your terminal:

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- help

Then follow the instructions shown on.

Run the helper script to deploy the application​

Using the deployment script, you can easily install the pdf2Data Editor by executing a series of commands.

important

All commands below are written for the case when the application directory is your current working directory in the terminal.

1. Generate Docker Compose configuration file​

Outcome: the docker-compose.yml file will be created in the Application directory

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- create-app-file --mode=editor-standalone|full-application

--mode specifying the type of pdf2Data Editor deployment. Depending on the selected option the script creates a configuration file to deploy UI with different functionality. There are two different options available:

  • --mode=editor-standalone - Lightweight UI. Minimal functionality, only basic Editor is available.
  • --mode=full-application - Fully-functional UI. Besides pdf2Data Editor, it includes also template management and Access control facilities

Alongside --mode, there are several other parameters available to configure the pdf2Data installation to your specific needs.

These include e.g --host and --port to customize the URL that is used to open pdf2Data Editor in the browser. If it should differ from the default value, which is localhost:80 The full list of supported parameters is available by adding the --help flag to the command above.

important

it is always possible to manually change parameters in the docker-compose.yml file before proceeding to the next step

2. Generate an environment configuration file​

Outcome: the .env file will be created in the application directory

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- create-config-file --mode=editor-standalone|full-application [--manager-admin-password] [--multi-workspace-mode]

--mode specifying the type of pdf2Data Editor deployment. Depending on the selected option the script creates a configuration file to deploy UI with different functionality. There are two different options available:

  • --mode=editor-standalone - UI with minimal functionality, where only basic pdf2Data template Editor is supposed to be deployed.
  • --mode=full-application - Fully-functional UI. Besides basic pdf2Data template Editor, it includes also template management and Access control facilities

In case of --mode=full-application you will be prompted to set up the password of the Global admin account. Password must have a length between 12 and 64 characters. It is highly recommended to log in and manually change the password after UI is deployed. It is also possible to setup the password using --manager-admin-password parameter but in that case it won't be hidden during typing, so using prompt is recommended.

caution

The user name for an account with global admin permissions is admin@email.com

You can also consider using the following optional flag:

--multi-workspace-mode - when present, pdf2Data Editor will be able to support more than one workspace so the users will be able to access only templates from the same workspace

important

You can customize the pdf2Data Editor deployment configuration by manually changing the parameters in the .env file before proceeding to the next step. Please refer to Customizing pdf2Data Editor application.

3. Deploy the application​

Before executing the following command, the application directory must contain valid docker-compose.yml and .env files.

kotlinc -script deploy-docker-compose-x.y.z.main.kts -- deploy

The execution of the deploy command may take a while. The script will pull the necessary Docker images from AWS ECR public registry (or Docker Hub for older versions) and runs all containers. In the full mode, there are 4 images:

ContainerAWS ECRDocker Hub (older versions)
manager-frontend4.2.0+4.0.0-4.1.3
manager-backend4.2.0+4.0.0-4.1.3
manager-database4.2.0+4.0.0-4.1.3
editor4.2.0+4.0.0-4.1.3